---
title: 手动安装 Astro
description: 如何通过 NPM、PNPM 或 Yarn 来手动安装 Astro。
---
import Button from '~/components/Button.astro'
import { FileTree } from '@astrojs/starlight/components';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
import ReadMore from '~/components/ReadMore.astro'

本指南将引导你如何手动安装和配置一个新的 Astro 项目。

:::tip[喜欢更快的入门方式？]
使用 [create astro CLI 向导](/zh-cn/install/auto/) 来快速创建新项目。
:::

#### 前提准备

- **Node.js** - `v18.14.1` 或更高版本。
- **文本编辑器** - 我们建议使用安装有 [Astro 官方扩展](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode)的 [VS Code](https://code.visualstudio.com/)。
- **终端（Terminal）** - Astro 可以通过其命令行界面 (CLI) 访问。

#### 安装

如果你不打算使用 `create astro` 命令工具来自动化创建项目，你可以根据以下说明来自行设置你的项目。

## 1. 创建项目目录

创建一个空目录，目录名称是你打算使用的项目名称，并导航到该目录。

```bash
mkdir my-astro-project
cd my-astro-project
```

在该目录内，创建 `package.json` 文件，该文件将管理你的项目依赖，包括 Astro，如果你不熟悉这种文件格式，可以运行下面的命令来直接创建一个。

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm init --yes
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm init 
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn init --yes
  ```
  </Fragment>
</PackageManagerTabs>

## 2. 安装 Astro

首先，需要在你的项目目录内安装 Astro 的项目依赖。

:::note[十分重要]
Astro 必须本地安装，不能全局安装。请确保**不要**运行 `npm install -g astro`、`pnpm add -g astro` 或者 `yarn add global astro`。
:::

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install astro
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add astro
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add astro
  ```
  </Fragment>
</PackageManagerTabs>

然后，使用下面的代码来替换 `package.json` 文件的 `scripts` 部分内容：

```json title="package.json" del={2} ins={3-6}
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  },
```

你将会在之后的教程中使用这些不同的命令来开始 Astro 项目。

## 3. 创建第一个页面

打开你的编辑器，在 `src/pages/` 目录下创建一个新文件 `index.astro`，这将会是你的第一个页面。

复制并粘贴以下内容到该页面 `index.astro` 内（包含 `---` 内的内容）。

```astro
---
// 欢迎来到 Astro！这些三横线所围住的代码
// 就是你的“组件 frontmatter”。它不会运行在浏览器中。
console.log('它运行在终端而非浏览器！');
---
<!-- 下面是你的“组件模板”。 这仅仅是 HTML，但是
     带有魔法点缀可以帮助构建更棒的模板。 -->
<html>
  <body>
    <h1>Hello, World!</h1>
  </body>
</html>
<style>
  h1 {
    color: orange;
  }
</style>
```

## 4. 创建静态文件

同样，你可以创建一个 `public/` 目录来存储你的静态文件。Astro 会在最后的编译中包含进这些文件，以便你可以在你的组件模板内安全地引用他们。

用编辑器在 `public/` 目录下创建一个 `robots.txt` 的文件，该文件将会告诉类似 Google 这样的搜索引擎怎样去对待该站点。

针对该教程，复制并粘贴以下内容至 `robots.txt` 内：

```diff title="public/robots.txt"
# 示例：运行所有爬虫抓取并索引你的站点。
# 全部语法：https://developers.google.com/search/docs/advanced/robots/create-robots-txt
User-agent: *
Allow: /
```

## 5. 创建 `astro.config.mjs` 配置文件

Astro 使用 `astro.config.mjs` 来配置项目。这个文件是可选的，你可以选择不配置它，但还是希望你现在创建该文件。

在你的项目根目录创建 `astro.config.mjs` 文件，并复制粘贴下面的内容至该文件内：

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({});
```

如果你想集成像 React、Svelte 这样的[UI 框架组件](/zh-cn/guides/framework-components/)或是使用其他类似 Tailwind 或 Partytown 这样的工具，你可以在[手动导入并配置集成](/zh-cn/guides/integrations-guide/)章节内获取更多信息。


<ReadMore>阅读 Astro 的 [API 配置参考](/zh-cn/reference/configuration-reference/) 章节来获得更多内容。</ReadMore>

## 6. 添加 TypeScript 支持

TypeScript 使用`tsconfig.json`进行配置。即使你不编写 TypeScript 代码，这个文件也很重要，因为 Astro 和 VS Code 等工具知道如何理解你的项目。 如果没有 `tsconfig.json` 文件，编辑器将不完全支持某些功能（如 npm 包导入）。

如果你打算编写 TypeScript 代码，建议使用 Astro 的`strict`或`strictest`的模板。 你可以在 [astro/tsconfigs/](https://github.com/withastro/astro/blob/main/packages/astro/tsconfigs/) 查看和比较三个模板配置。

在项目的根目录创建 `tsconfig.json`，并将下面的代码复制到其中。（你可以为 TypeScript 模板使用 `base`、`strict` 或 `strictest`）：

```json title="tsconfig.json" "base"
{
  "extends": "astro/tsconfigs/base"
}
```

最后，创建`src/env.d.ts`让 TypeScript 知道 Astro 项目中可用的环境类型：

```ts title="src/env.d.ts"
/// <reference types="astro/client" />
```

<ReadMore> 阅读 Astro 的 [TypeScript 设置指南](/zh-cn/guides/typescript/#设置) 来获取更多信息。</ReadMore>

## 7. 接下来

如果你按上述一步步操作，你的项目目录应该看上去像是这样：

<FileTree>
- node_modules/
- public/
  - robots.txt
- src/
  - pages/
    - index.astro
  - env.d.ts
- astro.config.mjs
- package-lock.json 或者 `yarn.lock`，`pnpm-lock.yaml`，等等。
- package.json
- tsconfig.json
</FileTree>

祝贺你，你现在可以使用 Astro 了！

如果你完成了这个指南的全部内容，你可以跳转至[步骤 2：启动 Astro](/zh-cn/install/auto/#2-启动-astro-)继续并学习如何首次运行 Astro。

